home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nspr / plstr.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  15KB  |  471 lines
  1. /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape Portable Runtime (NSPR).
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1998-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *   Roland Mainz <roland mainz@informatik.med.uni-giessen.de>
  24.  *
  25.  * Alternatively, the contents of this file may be used under the terms of
  26.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  27.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  28.  * in which case the provisions of the GPL or the LGPL are applicable instead
  29.  * of those above. If you wish to allow use of your version of this file only
  30.  * under the terms of either the GPL or the LGPL, and not to allow others to
  31.  * use your version of this file under the terms of the MPL, indicate your
  32.  * decision by deleting the provisions above and replace them with the notice
  33.  * and other provisions required by the GPL or the LGPL. If you do not delete
  34.  * the provisions above, a recipient may use your version of this file under
  35.  * the terms of any one of the MPL, the GPL or the LGPL.
  36.  *
  37.  * ***** END LICENSE BLOCK ***** */
  38.  
  39. #ifndef _plstr_h
  40. #define _plstr_h
  41.  
  42. /*
  43.  * plstr.h
  44.  *
  45.  * This header file exports the API to the NSPR portable library or string-
  46.  * handling functions.  
  47.  * 
  48.  * This API was not designed as an "optimal" or "ideal" string library; it 
  49.  * was based on the good ol' unix string.3 functions, and was written to
  50.  *
  51.  *  1) replace the libc functions, for cross-platform consistency, 
  52.  *  2) complete the API on platforms lacking common functions (e.g., 
  53.  *     strcase*), and
  54.  *  3) to implement some obvious "closure" functions that I've seen
  55.  *     people hacking around in our code.
  56.  *
  57.  * Point number three largely means that most functions have an "strn"
  58.  * limited-length version, and all comparison routines have a non-case-
  59.  * sensitive version available.
  60.  */
  61.  
  62. #include "prtypes.h"
  63.  
  64. PR_BEGIN_EXTERN_C
  65. /*
  66.  * PL_strlen
  67.  *
  68.  * Returns the length of the provided string, not including the trailing '\0'.
  69.  */
  70.  
  71. PR_EXTERN(PRUint32)
  72. PL_strlen(const char *str);
  73.  
  74. /*
  75.  * PL_strnlen
  76.  *
  77.  * Returns the length of the provided string, not including the trailing '\0',
  78.  * up to the indicated maximum.  The string will not be examined beyond the
  79.  * maximum; if no terminating '\0' is found, the maximum will be returned.
  80.  */
  81.  
  82. PR_EXTERN(PRUint32)
  83. PL_strnlen(const char *str, PRUint32 max);
  84.  
  85. /*
  86.  * PL_strcpy
  87.  *
  88.  * Copies the source string, up to and including the trailing '\0', into the
  89.  * destination buffer.  It does not (can not) verify that the destination
  90.  * buffer is large enough.  It returns the "dest" argument.
  91.  */
  92.  
  93. PR_EXTERN(char *)
  94. PL_strcpy(char *dest, const char *src);
  95.  
  96. /*
  97.  * PL_strncpy
  98.  *
  99.  * Copies the source string into the destination buffer, up to and including
  100.  * the trailing '\0' or up to and including the max'th character, whichever
  101.  * comes first.  It does not (can not) verify that the destination buffer is
  102.  * large enough.  If the source string is longer than the maximum length,
  103.  * the result will *not* be null-terminated (JLRU).
  104.  */
  105.  
  106. PR_EXTERN(char *)
  107. PL_strncpy(char *dest, const char *src, PRUint32 max);
  108.  
  109. /*
  110.  * PL_strncpyz
  111.  *
  112.  * Copies the source string into the destination buffer, up to and including 
  113.  * the trailing '\0' or up but not including the max'th character, whichever 
  114.  * comes first.  It does not (can not) verify that the destination buffer is
  115.  * large enough.  The destination string is always terminated with a '\0',
  116.  * unlike the traditional libc implementation.  It returns the "dest" argument.
  117.  *
  118.  * NOTE: If you call this with a source "abcdefg" and a max of 5, the 
  119.  * destination will end up with "abcd\0" (i.e., its strlen length will be 4)!
  120.  *
  121.  * This means you can do this:
  122.  *
  123.  *     char buffer[ SOME_SIZE ];
  124.  *     PL_strncpyz(buffer, src, sizeof(buffer));
  125.  *
  126.  * and the result will be properly terminated.
  127.  */
  128.  
  129. PR_EXTERN(char *)
  130. PL_strncpyz(char *dest, const char *src, PRUint32 max);
  131.  
  132. /*
  133.  * PL_strdup
  134.  *
  135.  * Returns a pointer to a malloc'd extent of memory containing a duplicate
  136.  * of the argument string.  The size of the allocated extent is one greater
  137.  * than the length of the argument string, because of the terminator.  A
  138.  * null argument, like a zero-length argument, will result in a pointer to
  139.  * a one-byte extent containing the null value.  This routine returns null
  140.  * upon malloc failure.
  141.  */
  142.  
  143. PR_EXTERN(char *)
  144. PL_strdup(const char *s);
  145.  
  146. /*
  147.  * PL_strfree
  148.  *
  149.  * Free memory allocated by PL_strdup
  150.  */
  151.  
  152. PR_EXTERN(void)
  153. PL_strfree(char *s);
  154.  
  155. /*
  156.  * PL_strndup
  157.  *
  158.  * Returns a pointer to a malloc'd extent of memory containing a duplicate
  159.  * of the argument string, up to the maximum specified.  If the argument
  160.  * string has a length greater than the value of the specified maximum, the
  161.  * return value will be a pointer to an extent of memory of length one
  162.  * greater than the maximum specified.  A null string, a zero-length string,
  163.  * or a zero maximum will all result in a pointer to a one-byte extent
  164.  * containing the null value.  This routine returns null upon malloc failure.
  165.  */
  166.  
  167. PR_EXTERN(char *)
  168. PL_strndup(const char *s, PRUint32 max);
  169.  
  170. /*
  171.  * PL_strcat
  172.  *
  173.  * Appends a copy of the string pointed to by the second argument to the
  174.  * end of the string pointed to by the first.  The destination buffer is
  175.  * not (can not be) checked for sufficient size.  A null destination
  176.  * argument returns null; otherwise, the first argument is returned.
  177.  */
  178.  
  179. PR_EXTERN(char *)
  180. PL_strcat(char *dst, const char *src);
  181.  
  182. /*
  183.  * PL_strncat
  184.  *
  185.  * Appends a copy of the string pointed to by the second argument, up to
  186.  * the maximum size specified, to the end of the string pointed to by the
  187.  * first.  The destination buffer is not (can not be) checked for sufficient
  188.  * size.  A null destination argument returns null; otherwise, the first 
  189.  * argument is returned.  If the maximum size limits the copy, then the
  190.  * result will *not* be null-terminated (JLRU).  A null destination
  191.  * returns null; otherwise, the destination argument is returned.
  192.  */
  193.  
  194. PR_EXTERN(char *)
  195. PL_strncat(char *dst, const char *src, PRUint32 max);
  196.  
  197. /*
  198.  * PL_strcatn
  199.  *
  200.  * Appends a copy of the string pointed to by the third argument, to the
  201.  * end of the string pointed to by the first.  The second argument specifies
  202.  * the maximum size of the destination buffer, including the null termination.
  203.  * If the existing string in dst is longer than the max, no action is taken.
  204.  * The resulting string will be null-terminated.  A null destination returns
  205.  * null; otherwise, the destination argument is returned.
  206.  */
  207.  
  208. PR_EXTERN(char *)
  209. PL_strcatn(char *dst, PRUint32 max, const char *src);
  210.  
  211. /*
  212.  * PL_strcmp
  213.  *
  214.  * Returns an integer, the sign of which -- positive, zero, or negative --
  215.  * reflects the lexical sorting order of the two strings indicated.  The
  216.  * result is positive if the first string comes after the second.  The
  217.  * NSPR implementation is not i18n.
  218.  */
  219.  
  220. PR_EXTERN(PRIntn)
  221. PL_strcmp(const char *a, const char *b);
  222.  
  223. /*
  224.  * PL_strncmp
  225.  * 
  226.  * Returns an integer, the sign of which -- positive, zero, or negative --
  227.  * reflects the lexical sorting order of the two strings indicated, up to
  228.  * the maximum specified.  The result is positive if the first string comes 
  229.  * after the second.  The NSPR implementation is not i18n.  If the maximum
  230.  * is zero, only the existance or non-existance (pointer is null) of the
  231.  * strings is compared.
  232.  */
  233.  
  234. PR_EXTERN(PRIntn)
  235. PL_strncmp(const char *a, const char *b, PRUint32 max);
  236.  
  237. /*
  238.  * PL_strcasecmp
  239.  *
  240.  * Returns an integer, the sign of which -- positive, zero or negative --
  241.  * reflects the case-insensitive lexical sorting order of the two strings
  242.  * indicated.  The result is positive if the first string comes after the 
  243.  * second.  The NSPR implementation is not i18n.
  244.  */
  245.  
  246. PR_EXTERN(PRIntn)
  247. PL_strcasecmp(const char *a, const char *b);
  248.  
  249. /*
  250.  * PL_strncasecmp
  251.  *
  252.  * Returns an integer, the sign of which -- positive, zero or negative --
  253.  * reflects the case-insensitive lexical sorting order of the first n characters
  254.  * of the two strings indicated.  The result is positive if the first string comes 
  255.  * after the second.  The NSPR implementation is not i18n.
  256.  */
  257.  
  258. PR_EXTERN(PRIntn)
  259. PL_strncasecmp(const char *a, const char *b, PRUint32 max);
  260.  
  261. /*
  262.  * PL_strchr
  263.  *
  264.  * Returns a pointer to the first instance of the specified character in the
  265.  * provided string.  It returns null if the character is not found, or if the
  266.  * provided string is null.  The character may be the null character.
  267.  */
  268.  
  269. PR_EXTERN(char *)
  270. PL_strchr(const char *s, char c);
  271.  
  272. /*
  273.  * PL_strrchr
  274.  *
  275.  * Returns a pointer to the last instance of the specified character in the
  276.  * provided string.  It returns null if the character is not found, or if the
  277.  * provided string is null.  The character may be the null character.
  278.  */
  279.  
  280. PR_EXTERN(char *)
  281. PL_strrchr(const char *s, char c);
  282.  
  283. /*
  284.  * PL_strnchr
  285.  * 
  286.  * Returns a pointer to the first instance of the specified character within the
  287.  * first n characters of the provided string.  It returns null if the character
  288.  * is not found, or if the provided string is null.  The character may be the
  289.  * null character.
  290.  */
  291.  
  292. PR_EXTERN(char *)
  293. PL_strnchr(const char *s, char c, PRUint32 n);
  294.  
  295. /*
  296.  * PL_strnrchr
  297.  *
  298.  * Returns a pointer to the last instance of the specified character within the
  299.  * first n characters of the provided string.  It returns null if the character is
  300.  * not found, or if the provided string is null.  The character may be the null
  301.  * character.
  302.  */
  303.  
  304. PR_EXTERN(char *)
  305. PL_strnrchr(const char *s, char c, PRUint32 n);
  306.  
  307. /*
  308.  * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr?
  309.  * Use strpbrk, strprbrk, strnpbrk or strnprbrk.
  310.  */
  311.  
  312. /*
  313.  * PL_strpbrk
  314.  *
  315.  * Returns a pointer to the first instance in the first string of any character
  316.  * (not including the terminating null character) of the second string.  It returns
  317.  * null if either string is null.
  318.  */
  319.  
  320. PR_EXTERN(char *)
  321. PL_strpbrk(const char *s, const char *list);
  322.  
  323. /*
  324.  * PL_strprbrk
  325.  *
  326.  * Returns a pointer to the last instance in the first string of any character
  327.  * (not including the terminating null character) of the second string.  It returns
  328.  * null if either string is null.
  329.  */
  330.  
  331. PR_EXTERN(char *)
  332. PL_strprbrk(const char *s, const char *list);
  333.  
  334. /*
  335.  * PL_strnpbrk
  336.  *
  337.  * Returns a pointer to the first instance (within the first n characters) of any
  338.  * character (not including the terminating null character) of the second string.
  339.  * It returns null if either string is null.
  340.  */
  341.  
  342. PR_EXTERN(char *)
  343. PL_strnpbrk(const char *s, const char *list, PRUint32 n);
  344.  
  345. /*
  346.  * PL_strnprbrk
  347.  *
  348.  * Returns a pointer to the last instance (within the first n characters) of any
  349.  * character (not including the terminating null character) of the second string.
  350.  * It returns null if either string is null.
  351.  */
  352.  
  353. PR_EXTERN(char *)
  354. PL_strnprbrk(const char *s, const char *list, PRUint32 n);
  355.  
  356. /*
  357.  * PL_strstr
  358.  *
  359.  * Returns a pointer to the first instance of the little string within the
  360.  * big one.  It returns null if either string is null.
  361.  */
  362.  
  363. PR_EXTERN(char *)
  364. PL_strstr(const char *big, const char *little);
  365.  
  366. /*
  367.  * PL_strrstr
  368.  *
  369.  * Returns a pointer to the last instance of the little string within the big one.
  370.  * It returns null if either string is null.
  371.  */
  372.  
  373. PR_EXTERN(char *)
  374. PL_strrstr(const char *big, const char *little);
  375.  
  376. /*
  377.  * PL_strnstr
  378.  *
  379.  * Returns a pointer to the first instance of the little string within the first
  380.  * n characters of the big one.  It returns null if either string is null.  It
  381.  * returns null if the length of the little string is greater than n.
  382.  */
  383.  
  384. PR_EXTERN(char *)
  385. PL_strnstr(const char *big, const char *little, PRUint32 n);
  386.  
  387. /*
  388.  * PL_strnrstr
  389.  *
  390.  * Returns a pointer to the last instance of the little string within the first
  391.  * n characters of the big one.  It returns null if either string is null.  It
  392.  * returns null if the length of the little string is greater than n.
  393.  */
  394.  
  395. PR_EXTERN(char *)
  396. PL_strnrstr(const char *big, const char *little, PRUint32 max);
  397.  
  398. /*
  399.  * PL_strcasestr
  400.  *
  401.  * Returns a pointer to the first instance of the little string within the big one,
  402.  * ignoring case.  It returns null if either string is null.
  403.  */
  404.  
  405. PR_EXTERN(char *)
  406. PL_strcasestr(const char *big, const char *little);
  407.  
  408. /*
  409.  * PL_strcaserstr
  410.  *
  411.  * Returns a pointer to the last instance of the little string within the big one,
  412.  * ignoring case.  It returns null if either string is null.
  413.  */
  414.  
  415. PR_EXTERN(char *)
  416. PL_strcaserstr(const char *big, const char *little);
  417.  
  418. /*
  419.  * PL_strncasestr
  420.  *
  421.  * Returns a pointer to the first instance of the little string within the first
  422.  * n characters of the big one, ignoring case.  It returns null if either string is 
  423.  * null.  It returns null if the length of the little string is greater than n.
  424.  */
  425.  
  426. PR_EXTERN(char *)
  427. PL_strncasestr(const char *big, const char *little, PRUint32 max);
  428.  
  429. /*
  430.  * PL_strncaserstr
  431.  *
  432.  * Returns a pointer to the last instance of the little string within the first
  433.  * n characters of the big one, ignoring case.  It returns null if either string is
  434.  * null.  It returns null if the length of the little string is greater than n.
  435.  */
  436.  
  437. PR_EXTERN(char *)
  438. PL_strncaserstr(const char *big, const char *little, PRUint32 max);
  439.  
  440. /*
  441.  * PL_strtok_r
  442.  *
  443.  * Splits the string s1 into tokens, separated by one or more characters
  444.  * from the separator string s2.  The argument lasts points to a
  445.  * user-supplied char * pointer in which PL_strtok_r stores information
  446.  * for it to continue scanning the same string.
  447.  *
  448.  * In the first call to PL_strtok_r, s1 points to a string and the value
  449.  * of *lasts is ignored.  PL_strtok_r returns a pointer to the first
  450.  * token, writes '\0' into the character following the first token, and
  451.  * updates *lasts.
  452.  *
  453.  * In subsequent calls, s1 is null and lasts must stay unchanged from the
  454.  * previous call.  The separator string s2 may be different from call to
  455.  * call.  PL_strtok_r returns a pointer to the next token in s1.  When no
  456.  * token remains in s1, PL_strtok_r returns null.
  457.  */
  458.  
  459. PR_EXTERN(char *)
  460. PL_strtok_r(char *s1, const char *s2, char **lasts);
  461.  
  462. /*
  463.  * Things not (yet?) included: strspn/strcspn, strsep.
  464.  * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero.
  465.  * Any and all i18n/l10n stuff.
  466.  */
  467.  
  468. PR_END_EXTERN_C
  469.  
  470. #endif /* _plstr_h */
  471.